Rust I18n
π― Let's make I18n things to easy!
Rust I18n is a crate for loading localized text from a set of YAML mapping files. The mappings are converted into data readable by Rust programs at compile time, and then localized text can be loaded by simply calling the provided t!
macro.
Unlike other I18n libraries, Rust I18n's goal is to provide a simple and easy-to-use API.
The API of this crate is inspired by ruby-i18n and Rails I18n.
Features
- Codegen on compile time for includes translations into binary.
- Global
t!
macro for loading localized text in everywhere. - Use YAML for mapping localized text, and support mutiple YAML files merging.
cargo i18n
Command line tool for checking and extract untranslated texts into YAML files.
Usage
Add crate dependencies in your Cargo.toml and setup I18n config:
[]
= "1"
Load macro and init translations in lib.rs
// Load I18n macro, for allow you use `t!` macro in anywhere.
extern crate rust_i18n;
// Init translations for current crate.
i18n!;
// Or just use `i18n!`, default locales path is: "locales" in current crate.
i18n!;
// Config fallback missing translations to "en" locale.
// Use `fallback` option to set fallback locale.
i18n!;
Or you can import by use directly:
// You must import in each files when you wants use `t!` macro.
use t;
i18n!;
Make sure all YAML files (containing the localized mappings) are located in the locales/
folder of the project root directory:
.
βββ Cargo.lock
βββ Cargo.toml
βββ locales
β βββ en.yml
β βββ zh-CN.yml
β βββ zh-HK.yml
βββ src
β βββ main.rs
βββ sub_app
β βββ locales
β β βββ en.yml
β β βββ zh-CN.yml
β β βββ zh-HK.yml
β βββ src
β β βββ main.rs
β βββ Cargo.toml
In the YAML files, specify the localization keys and their corresponding values, for example, in en.yml
:
hello: Hello world # A simple key -> value mapping
messages:
hello: Hello, %{name} # A nested key.sub_key -> value mapping, in this case "messages.hello" maps to "Hello, %{name}"
And example of the zh-CN.yml
:
hello: δ½ ε₯½δΈη
messages:
hello: δ½ ε₯½οΌ%{name} (%{count})
Loading Localized Strings in Rust
Import the t!
macro from this crate into your current scope:
use t;
Then, simply use it wherever a localized string is needed:
t!;
// => "Hello world"
t!;
// => "δ½ ε₯½δΈη"
t!;
// => "Hello, world"
t!;
// => "Hello, world"
t!;
// => "δ½ ε₯½οΌJason (2)"
t!;
// => "δ½ ε₯½οΌJason (5)"
Setting and Getting the Global Locale
You can use rust_i18n::set_locale
to set the global locale at runtime, so that you don't have to specify the locale on each t!
invocation.
;
let locale = locale;
assert_eq!;
set_locale
Extractor
We provided a cargo i18n
command line tool for help you extract the untranslated texts from the source code and then write into YAML file.
You can install it via cargo install rust-i18n
, then you get cargo i18n
command.
Configuration for cargo i18n
command
π‘ NOTE: package.metadata.i18n
config section in Cargo.toml is just work for cargo i18n
command, if you don't use that, you don't need this config.
[]
# The available locales for your application, default: ["en"].
# available-locales = ["en", "zh-CN"]
# The default locale, default: "en".
# default-locale = "en"
# Path for your translations YAML file, default: "locales".
# This config for let `cargo i18n` command line tool know where to find your translations.
# You must keep this path same as the one you pass to method `rust_i18n::i18n!`.
# load-path = "locales"
Rust I18n providered a i18n
bin for help you extract the untranslated texts from the source code and then write into YAML file.
# Now you have `cargo i18n` command
After that the untranslated texts will be extracted and saved into locales/TODO.en.yml
file.
You also can special the locale by use --locale
option:
Run cargo i18n -h
to see details.
<source> Path
Debugging the Codegen Process
The RUST_I18N_DEBUG
environment variable can be used to print out some debugging infos when code is being generated at compile time.
Example
A minimal example of using rust-i18n can be found here.
I18n Ally
I18n Ally is a VS Code extension for helping you translate your Rust project.
You can add i18n-ally-custom-framework.yml to your project .vscode
directory, and then use I18n Ally can parse t!
marco to show translate text in VS Code editor.
License
MIT